Prompt Dialogs "All is not gold that outward sheweth bright" Lydgate Introduction In Chapter 4 you learned about the message functions such as PromptOK and PromptYesNo. These functions make it easy to display a message and prompt the user to select a button. The GOLDREAD unit takes the feature one step further and allows the user to input data such as strings, integers and even select a radio button. If you want to prompt the user to input a single standard field type, you don't need to build a custom IO form, just use GOLDREAD's prompt functions. Figure 9.1 shows the PromptStr function in action. Figure 9.1 The PromptStr dialog A Prompt Function Summary List below is a summary of the prompt functions supplied in the GOLDREAD unit: PromptStr(X,Y,StrFldLen:byte;Lab,Tit:StrScreen; Default:string; Caps:boolean): string; Prompts the user to enter a string. If the field length is too long for the dialog, Gold will automatically use a scrollable string field. PromptStr will optionally convert all input to uppercase. PromptNum(X,Y:byte;Lab,Tit:StrScreen;Default,Min,Max:LongInt; Spin:boolean): longint; Prompts the user to input a whole number within the specified range. The field optionally displays spinners to allow the user to scroll through a range of numbers. PromptReal(X,Y:byte;Lab,Tit:StrScreen;Fmat:string;Default, Min,Max:extended): extended; Prompts the user to input a real number within the specified range. The field optionally displays spinners to allow the user to scroll through a range of numbers. PromptFixedReal(X,Y:byte;Lab,Tit:StrScreen;WLen,DP:byte;Default, Min,Max,Delta:extended;Spin:boolean): extended; Like FixedReal except the field has a fixed decimal place. PromptDate(X,Y:byte;Lab,Tit:StrScreen;Fmat:gDate;Default, Min,Max:Dates;Spin,Drop:boolean): Dates; Prompts the user to enter a date within the specified range. All the Gold date formats are supported. The field optionally displays spinners to allow the user to scroll through a range of numbers, as well as an optional drop down calendar. PromptRadio(X,Y:byte;Lab,Tit:StrScreen;Fields:string; Default:byte): byte; Prompts the user to select an item from a list of up to 13 radio button items. The radio button text for all the items is defined in a single string, with each option delimited by the '|' character. PromptColor(X,Y,Default:byte;Cmt,Tit:StrScreen): byte; Prompts the user to select a display attribute, i.e. background and foreground colors. This dialog is highly customizable. Refer to the section Prompting for Colors for more information. The user can optionally escape from these dialogs. If you need to know whether the user escaped, check the value of the variable ReadVars.LastAction, which will be set to Escaped if the user selects the Cancel button, or clicks on the close icon. Here are a few tips to help you customize the dialog's appearance: Window Position - Each function accepts X and Y parameters which identify the upper left coordinates of the dialog window. If X is specified as zero, the dialog will be horizontally centered. Similarly, if Y is specified as zero, the dialog will be vertically centered. You guessed it, if both X and Y are set to zero, the dialog will be automatically positioned in the middle of the display. Window Style - You can customize the prompt window style by assigning a value in the range 1 to 9 to the variable ReadVars.PromptStyle. At program start-up the default window style is set to the same style as PromptOK, i.e. the style specified in WinVars.PromptStyle. Label Position - By default, the optional field label is positioned to the left of the field (except for PromptRadio). To position the label above the field, simply start the label with the '^' character, e.g. '^Enter your name'. Number Ranges - The number and prompt related prompts require that you specify a maximum and minimum acceptable value. If you want the user to be able to enter any value (i.e. disable the range limits), specify the min and max values as zero. Controlling Gaps - The gaps or whitespace to the left and right of the dialog, i.e. the area between the input field and the window border, is controlled by the variable ReadVars.OutsideGap. The default value is 2. The gap between the buttons is similarly controlled by the variable ReadVars.ButtonGap, which also has a default of 2 characters. Run the demo files DEMRD1.PAS through DEMRD7.PAS to see the prompt functions in action. Prompting for Passwords In some instances, you may not want the user's input to be echoed to the screen. For example, you may be prompting the user to enter a password. You can force the PromptStr function to echo an asterisk to the screen whenever a character is typed by setting the boolean variable ReadVars.Password to TRUE. The demo program DEMRD9.PAS illustrates this technique. Prompting for Colors The PromptColor function is designed for applications that allow the end users to select their own display colors. It displays two lists of colors; one for the foreground and one for the background. A visual sample of the active selection is displayed. You can assign a function to display a custom visual sample by calling the function AssignTextSampleHook. By default, the dialog only allows two or three lines in which to display the sample. If you want more space to display the sample, change the value of the variable ReadVars.ColorWinDepth to reflect the total number of lines required in the window. The sample hook must be declared as a far procedure at the root level, and must be passed two byte parameters -- the second parameter being a variable. The first parameter identifies the active field, and the second parameter is a refresh code which informs Gold about which fields need to be redrawn -- either set the second parameter to RefreshNone or RefreshAll. These constants are declared in the GOLDIO unit. From within the hooked procedure you can ascertain the current values for the foreground and background by inspecting the variables ReadVars.ForegroundByte and ReadVars.BackgroundByte. Listed below is an extract of the demo file DEMRD8.PAS which customizes the color hook: {$F+} procedure NewTextHook(CurrentField:byte;var Refresh:byte); {} var A: byte; begin with ReadVars do begin A := Cattr(pred(ForeGroundByte), pred(BackGroundByte)); Refresh := RefreshOthers; case CurrentField of 0,1,2,3: ; 3: CheckBrightFlags(A); else Refresh := RefreshNone; end; if Refresh = RefreshOthers then begin Box3D(2,10,46+ 2*Ord(not PromptStyle in [7,8]),18, BlackOnCyan,WhiteOnCyan,8); PartClear(5,11,43+2*Ord(not PromptStyle in [7,8]),17,A,' '); WriteAT(5,11,A,'Help on the Colors dialog'); WriteAT(5,13,A,'GOLD includes SampleHook...'); WriteAT(5,14,A,'permits the developer ...'); WriteAT(5,15,A,'to the PromptColor ....'); end; end; end; { NewTextHook } {$F-} begin with ReadVars do begin ColorWinDepth := 19; PromptStyle := 4; BlinkingOn := false; end; UseCustomChars; MouseShow(true); AssignTextSampleHook(NewTextHook); TmpColor := PromptColor(0,4,RedOnCyan,'Pick color', 'GoldRead Color Input'); ..... end. By default, the PromptColor background color list only includes the first 8 colors, i.e. the bright colors are excluded. Set the boolean variable ReadVars.Use16BgndColors variable to true to instruct Gold to support all 16 colors for the background field. Adding a Help Routine By default, the prompt dialogs do not include a help button. However, a help button will automatically appear when you use the following procedure: AssignReadHelpHook(PFHook: PromptHelpHook); Assigns a help procedure to the Prompt dialogs in GOLDREAD. The passed procedure must be declared far and have no passed parameters. The hooked procedure will be called whenever the user selects the Help button. To subsequently remove the Help button, call the procedure RemoveReadHelpHook before displaying the dialog. Run DEMRD10.PAS for a demonstration of the custom help facility. Customizing the Dialog Colors To customize the display colors of the prompt dialogs, use the GoldSetColor function to set one of the following color components: PromptBorder1 PromptBorder2 PromptTitle PromptBody PromptButtonHiHot PromptButtonHi PromptButtonNormHot PromptButtonNorm PromptButtonDefHot PromptButtonDef PromptIcons PromptBodyHi PromptNormalCmt PromptHiCmt PromptEditErase PromptEditNorm PromptEditHi Listed below is an extract from DEMRD11.PAS which updates all the prompt colors: procedure CustomizeColors; {} begin GoldSetColor(PromptBorder1,LightRedOnRed); GoldSetColor(PromptBorder2,LightRedOnRed); GoldSetColor(PromptTitle,WhiteOnRed); GoldSetColor(PromptBody,LightGrayOnRed); GoldSetColor(PromptButtonHiHot,WhiteOnMagenta); GoldSetColor(PromptButtonHi,YellowOnMagenta); GoldSetColor(PromptButtonNormHot,YellowOnMagenta); GoldSetColor(PromptButtonNorm,LightgrayOnMagenta); GoldSetColor(PromptButtonDef,LightgrayOnMagenta); GoldSetColor(PromptButtonDefHot,LightcyanOnMagenta); GoldSetColor(PromptIcons,LightcyanOnRed); GoldSetColor(PromptBodyHi,WhiteOnRed); GoldSetColor(PromptNormalCmt,YellowOnRed); GoldSetColor(PromptHiCmt,WhiteOnRed); GoldSetColor(PromptEditErase,WhiteOnGreen); GoldSetColor(PromptEditNorm,LightGrayOnMagenta); GoldSetColor(PromptEditHi,WhiteOnMagenta); end; { CustomizeColors } Customizing the Button Text and Error Messages International developers (and developers in Louisiana) may want to translate the strings used in the prompt dialogs. The button text along with the button hotkeys use the common buttons declared in GOLDWIN. You can modify the default buttons by changing the values of the following WinVars variables (shown with their default assignments): with WinVars do begin OKButStr := ' ~O~K '; OKHotKey := 280; { Alt+O } CancelButStr := ' ~C~ancel '; CancelHotKey := 302; { Alt+C } HelpButStr := ' ~H~elp '; HelpHotKey := 291; end; The PromptColor function uses an additional set of strings, which are all defined in the ReadVars record. Listed below are the string variables in ReadVars along with their default values: BrightLabel := 'B~r~ight background'; FGLabel := '~F~oreground'; BGLabel := '~B~ackground'; FGHotKey := 289; { Alt+F } BGHotKey := 304; { Alt+B } BrightLabelHotKey := 275; { Alt+R } SampleText := ' Text Text Text '; SampleTxtHdr := 'Sample Text'; LowerSet := 'Black|Blue|Green|Cyan|Red| Magenta|Brown|LightGray'; UpperSet := 'DarkGray|LightBlue|LightGreen|LightCyan| LightRed|LightMagenta|Yellow|White'; Error Handling All the prompt functions discussed in this chapter have the potential to fail. The most probable cause of error is a lack of memory to construct the window. After calling one of the functions, always call the function LastReadError to see whether the operation was successful.